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It the inception of its "Blue 
Ninja" marketing campaign, 
IBM touted OS/2, Version 2.0, 
as "a better DOS than DOS, a 
better Windows than Win- 
dows." More recently, IBM has 
backed down a bit from these 
claims, but the company is still 
emphasizing the superior relia- 
bility of OS/2 running Windows applica- 
tions as opposed to Windows running 
Windows applications. Nobody finds this 
particularly hard to believe. Just about 
lyone who runs Windows has experi- 
enced at least one or two major crashes, 
and those of us who develop Windows 
programs are privileged to watch the en- 
tire system regularly fall on its face. I just 
love it when I type Exit in a Windows 
DOS box, only to have the screen flash 
horribly and then find myself again at the 
DOS prompt — except that Windows and 
all the applications I was running while 
I was temporarily using the DOS box are 
history. This brings up the obvious ques- 
tion: If both OS/2 and Windows run in 
protected mode, just why is Windows 
such a fragile environment? 

The primary reason, of course, is that 
Windows is a multitasking, graphical en- 
vironment layered on top of a single- 
tasking, character-oriented operating 
system, and the relationship between the 
two is not, to put it kindly, elegant. Win- 
dows relies on all sorts of undocumented 
DOS structures and functions, captures 
many DOS and ROM BIOS interrupt 
vectors, and inserts legions of little ten- 
drils and hooks into DOS's innards. 

loreover, Windows contains its own 
.nemory manager and its own suite of de- 
vice drivers, which must somehow coexist 
with the DOS memory manager and de- 
vice drivers. This is a classic example of 



a statue of gold (well, okay, maybe silver) 
with feet of clay. 

For the first two versions of Windows, 
there was quicksand under the feet of 
clay, as well: the Intel 80x86 real mode, 
which required Windows to use a truly 
Byzantine scheme for virtual memory 
management and allowed an errant ap- 
plication to scribble anywhere in mem- 
ory. In spite of this hardware deficiency, 

A sample program lets 
you explore ToolHelp s 
facilities for installing 
a notification callback 
routine for Windows 
API parameter errors. 



the earliest versions of Windows did not 
even make a token attempt to check the 
parameters that were passed to an API 
function by an application before using 
them! If the application supplied a bad 
pointer or handle, the function call would 
not only fail but it could take the whole 
system down with it. Sometimes, unfor- 
tunately, the damage would be subtle 
enough that the application or the system 
would continue to run for quite a while 
before staggering to a halt, making the 
original cause of the problem nearly im- 
possible to track down. 

The basic instability of Windows has 
always been complicated by the fact that 
Windows applications have tended to be, 
frankly, very buggy. Try running any 
large first- or second-generation Win- 
dows application on a Windows system 



with the debugging kernel installed and 
you'll be astonished at the number of di- 
agnostic messages. Microsoft deserves 
most of the blame for this. In the earliest 
days of Windows, the message traffic, the 
relationships between events, and the 
interdependencies of Windows API func- 
tions were very poorly documented; the 
debugging facilities were crude; and the 
debugging hooks were a closely guarded 
secret, which prevented third parties 
from supplying more capable debuggers. 
Consequently, most developers had only 
a dim understanding of how the system 
as a whole really fit together, and they 
built their programs by cutting and past- 
ing source code from other, previously 
working programs or by cloning source 
code published by Windows gurus like 
Charles Petzold and Michael Geary. 

Windows 3.0, which was the first ver- 
sion of the operating environment to run 
in protected mode, brought with it the 
dreaded UAE (Unrecoverable Applica- 
tion Error). It's important to note, how- 
ever, that UAEs were (for the most part) 
not a symptom of new problems with ap- 
plications and Windows itself; rather they 
were an unmasking of old problems. In 
protected mode, use of a bad pointer 
caused an immediate General Protection 
fault (a special hardware interrupt) in- 
stead of an unpredictable amount of 
damage and a crash somewhere down the 
road. The Windows 3.0 developers were 
apparently so rattled by the whole con- 
cept of GP faults that they decided to 
handle them all in a very conservative 
way: terminating the active application 
and displaying a scary dialog box that 
warned the user to restart his machine 
immediately or suffer the consequences, 
even though in the vast majority of cases 
the system itself was undamaged. Inexpli- 
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cably, they still made no attempt to per- 
form sanity checks on the parameters of 
Windows function calls. Windows was 
probably the only general-purpose multi- 
tasking environment in computer history 
to place such total faith in the correctness 
of the applications that ran under its 
control. 

Microsoft didn't really get interested 
in improving the robustness of Windows 
until after the Great Divorce from IBM, 
when it suddenly became apparent that 
the stability of Windows was going to be 
a crucial competitive issue. During the 
period between Windows 3.0 and 3.1, 
Microsoft took many laudable — if sadly 
overdue — steps to improve life for Win- 
dows programmers. A utility called Dr. 
Watson, which trapped application er- 
rors and wrote diagnostic information to 
a file on-disk, was distributed to develop- 
ers and users via bulletin boards and on- 
line services. A TEST program was pro- 
vided that allowed programmers to exer- 
cise their applications under a variety of 
stressful conditions. A single-screen de- 
bugger was released, and many previ- 
ously mysterious aspects of the system 
were cleaned up and documented. Micro- 
soft also implemented a new dynamic 
link library, called TOOLHELP.DLL, 
that gave applications access to certain 
internal Windows structures and made it 
possible to write debuggers using offi- 
cially supported interfaces. The Tool- 



TheToolHelp Functions 


Function category 


Function names 


Window information 


ClassFirstO, ClassNextO, GetClasslnfoO 


Task and module 


ModuleFirstf), ModuleNextO, 


information 


ModuleFindHandleO, ModuleFindNameO, 




TaskFirstO, TaskNextf), TaskFindHandleO 


Memory information 


SystemHeaplnfoO, MemManlnfoO 


Global heap information 


GloballnfoO, GlobalFirstl), GlobalNextO, 




GlobalEntryHandle(),GlobalEntryModule() 


Local heap information 


LocallnfoO, LocalFirstO, LocalNextO 


Stack information!) 


St a c kTra c e Fi rstO, Sta c kTra c e N ext( ), 




StackTraceCSIPFirstl) 


Execution timing 


TimerCountO 


information 




Huge object access 


MemoryReadl), MemoryWriteO, 




GlobalHandleToSeK) 


Error callbacks 


InterruptRegisterl), InterruptUnRegisterO, 




NotifyRegisterl), NotifyUnRegisterO 


Process control 


TaskGetCSlPO, TaskSetCSlPO, TaskSwitchO, 




TerminateAppO 



Figure 1: A summary of the functions exported by TOOLHELP.DLL. 
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Help functions are summarized in Figure 
1. This library was licensed, along with 
the Windows header files and import li- 
braries, to third-party developers, which 
set off an explosive evolution in Windows 
programming tools. 

Finally, with the release of Windows 
3.1; Microsoft made TOOLHELP.DLL 
and Dr. Watson an integral part of the 
retail Windows package and incorpo- 
rated parameter validation and local re- 
boot into the system. Parameter valida- 
tion means that Windows checks most 
arguments for an application function 
call for "reasonable" values before exe- 
cuting the function. If a parameter is bo- 
gus, Windows will take what it feels to 
be an appropriate action. In some cases, 
it simply ignores the function call or re- 
turns an error to the calling program; in 
others, it gives the user the opportunity 
to abort the application. Local reboot 
means that Windows traps the Ctrl-Alt- 
Del key combination and gives the user 
the option of simply killing the current 
program rather than resetting the entire 
system. 

THE BADAPP PROGRAM To give you a 
test-bed for playing around with Win- 
dows 3.1's parameter validation, fault 
trapping. Dr. Watson, and local reboot, 
I've written a toy program called BAD- 
APP. The C source code for BADAPP 
is found in Figure 2 (for reasons of space, 
the header file, module definition file, 
and resource script are 
not shown here). BAD- 
APP uses the same ta- 
ble-driven structure for 
message handling and 
menu decoding that I 
introduced in my previ- 
ous series of columns on 
the Windows 3.1 Com- 
mon Dialogs. All of the 
source files and the exe- 
cutable file for BAD- 
APP can be down- 
loaded as BADAPP 
.ZIP from the Program- 
ming Forum on PC 
MagNet, or can be 
obtained by writing PC 
Magazine (see instruc- 
tions at the end of this 
column). 

The source code for 
BADAPP is so simple 



that it should be self-explanatory, ai 
BADAPP is a pretty trivial program from 
the user's point of view as well. The File 
pop-up menu has only one item, Exit, 
that is used to shut down the program in 
the "normal" manner. The Crash pop-up 
menu offers several choices: GP Fault, 
Divide by Zero, Pass Bad Pointer, Infi- 
nite Loop, and Pass Bad HDC (device 
context handle). Each of the Crash menu 

Parameter validation 
means that Windows 
checks most arguments for 
an application junction 

call for "reasonable" 
values before executing 
thefunction. 

items tests a different aspect of Window 
3.1's ability to detect and protect itst 
from severe application bugs. You'll no- 
tice some interesting differences in the 
way Windows handles these five cases. 

Selection of the GP Fault menu item 
causes control to pass to the DoMenuGP- 
FaultQ routine, which allocates a far 
pointer on the stack, initializes it to zero, 
and then dereferences it. Windows inter- 
cepts the resulting GP fault and puts up 
a Close or Ignore dialog box. If you pick 
Close. Windows terminates BADAPP 
unilaterally. If you choose Ignore, Win- 
dows allows the application to continue 
its execution. This has no particularly bad 
implications in the BADAPP program, 
because BADAPP doesn't do anything 
with the data it is fetching via the invalid 
pointer. A real application would, of 
course, end up processing garbage if the 
user picked Ignore, most likely leading to 
another GP fault or some other catastro- 
phe within a very short time. 

The Divide by Zero and Pass Bad 
Pointer menu commands cause BAD- 
APP to call the DoMenuZeroDiv() and 
DoMenuBadPtrQ routines, respective! 
The first of these routines demands an in 
teger-divide-by-zero operation that Bor- 
land C++, for performance reasons, com- 
piles as in-line code without any error 
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decking. The second routine calls the 
/indows API function Message- 
Box with a null pointer for the string to 
be displayed within the message box. In 
both cases, Windows shuts down the ap- 
plication immediately without any option 
to continue. The handling of Pass Bad 
Pointer is a little surprising, because Win- 
dows could use the Intel 80286 VERR in- 
struction to check out the pointer "for 
free" before trying to use it, and just fail 
the function call if the pointer was invalid. 
Apparently, however, Windows just de- 
references the pointer blindly, a GP fault 
occurs within the Windows kernel, and 



all this leads to a UAE condition for the 
application. 

If you pick Infinite Loop, BADAPP 
calls its DoMenuHang routine, which 
consists mainly of a while(TRUE){) 
structure, and the entire system enters a 
funny state. The screen looks okay and 
the mouse pointer will still move around 
on the screen, but nothing else works. 
This is because the mouse generates in- 
terrupts, and interrupts are not masked 
(since the infinite loop occurs at the ap- 
plication level rather than within the 
Windows kernel), so the mouse driver 
can continue to monitor the mouse's lo- 



cation and update the screen accordingly. 
All other Windows activities, however, 
necessarily come to a screeching halt be- 
cause Windows multitasking is coopera- 
tive rather than preemptive. If the appli- 
cation is in an infinite loop, it never 
processes its own queue messages or 
yields control, and other applications 
never get a chance to process messages, 
either. If you press the Ctrl-Alt-Del key 
combination, a keyboard interrupt oc- 
curs, the keyboard driver gets control, 
and it calls the Windows local reboot rou- 
tine, which gives you the choice to con- 
tinue execution, abort the current appli- 



BADAPP.C 

1 of2 



// BADAPP - Application Error Testbed for Windows 3.1 

// Copyright (C) 1992 Ray Duncan 

// Ziff Davis Publishing * PC Magazine 



tdefine dim(x) (sizeof(x) / sizeof (x [0 ] ) ) 

tf include "windows . h" 
Sinclude "badapp . h" 

HANDLE hlnst; 
HWND hFrame; 

char sz Short AppName [ ] = *BadApp"; 

char szAppName[] = -BadApp - UAE Tester"; 

char szMenuName[] = "BadAppHenu" ; 

truct decodeWord { 
UINT Code; 

LONG ('Fxn)(HWND, UINT, UINT, LONG) ; } 



// returns no. of elements 



// module instance handle 
// handle for frame window 

// short application name 
// long application name 
// name of menu resource 

// structure associates 
// messages or menu IDs 
// with a function 



// Table of window messages supported by FrameWndProc { ) 
// and the functions which correspond to each message. 
// 

struct decodeWord messages [] = { 
WM_PAINT, DoPaint, 
WM_COMMAND, DoCommand, 
WM_DESTROY , DoDestroy, J ; 

// 

// Table of menubar item IDs and their corresponding functions. 
// 

struct decodeWord menuitems[] = { 
IDM_EXIT, DoMenuExit, 
IDM_GPFAULT , DoMenuGPFault, 
IDM^HANG, DoMenuHang, 
IDM_ZERODI V , DoMenuZeroDi v , 
IDM_BADHDC , DoMenuBadHDC , 
IDM_BADPTR, DoMenuBadPtr , } ; 

// 

// WinMain — entry point for this application from Windows. 

// 

INT API ENTRY WinMain (HANDLE hlnstance, 

HANDLE hPrevInstance, LPSTR lpCmdLine, INT nCmdShow) 

{ 



hlnst = hlnstance; 

if ( IhPrevlnstance) 

if ( !InitApplication (hlnstance) ) 
return (FALSE) ; 

if ( ! Initlnstance (hlnstance, nCmdShow) ) 
return (FALSE) ; 

while(GetMessage(&msg, NULL, 0, 0) ) 
{ 

TranslateMessage(&msg) ; 
DispatchMessage(Sjnsg) ; 



Termlnstance < hlnstance) ; 
retum(msg.wParam) ; 



// save this instance handle 

//if first instance, 

// register window class 

// exit if couldn't register 

// create this instance's window 
// exit if create failed 

// while message != WM_QUIT 

// translate virtual key codes 
/ / dispatch message to window 



// clean up for this instance 
// return code = WM_QUIT value 



// InitApplicstiun 



ylutwl initialization code for this application. 



BOOL InitApplicationfHANDLE hlnstance) 
{ 

WNDCLASS wc ; 
// set parameters for frame window class 

wc. style = CS_HREDRAW j CS_VREDRAW; // class style 

wc . lpfnWndProc = FrameWndProc; // class callback function 

wc .cbClsExtra =0; // extra per-class data 

wc.cbWndExtra =0; // extra per-window data 

wc. hlnstance = hlnstance; // handle of class owner 

wc.hlcon = Loadlcon (hlnst , "BadAppIcon" ) ; // skull icon 

wc.hCursor = LoadCursor (NULL, IDC_ARROW) ; // default cursor 

wc . hbrBackground = GetStockObject (WHITE_BRUSH) ; // background color 

wc . IpszMenuName = szMenuName; // name of menu resource 

// name of window class 



retum(RegisterClass(&wc) ) ; 



// register class, return status 



// Initlnstance instance initialization code for this application. 

BOOL Initlnstance (HANDLE hlnstance, int nCmdShow) 



hFrame = CreateWindow ( 


II 


create frame window 


szShort AppName, 


// 


window class name 


sz AppName, 


// 


text for title bar 


WS_OVERLAPPEDWINDOW , 


// 


window style 


CW_USEDEFAULT, CW_USE DEFAULT , 


II 


default position 


CW_USEDEFAULT , CW_USEDEFAULT , 


It 


default size 


NULL, 


II 


no parent window 


NULL, 


It 


use class default menu 


hlnstance. 


II 


window owner 


NULL) ; 


It 


unused pointer 


if ( IhFrame) return (FALSE) ; 


It 


error, can't create window 


ShowWindow (hFrame, nCmdShow) ,- 


II 


make frame window visible 


UpdateWindow (hFrame) ; 


It 


force WM_PAINT message 


return (TRUE) ; 


II 


return success flag 



// Termlnstance — instance termination code for this application. 



BOOL Termlnstance (HANDLE hlnstance) 



return (TRUE) j 



// return success flag 



/ / FrameWndProc 



callback function for application frame window. 



LONG FAR APIENTRY FrameWndProc (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 



int i; 



// scratch variable 



0; i < dim (messages ) ; i++) 



I ! decode window message and 
// run corresponding function 



for(i 

{ 

if(wMsg == messages [i] .Code) 

return{ ( *messages [ i J .Fxn) (hWnd, wMsg, wParam, lParam) ) ; 

} 

retum(DefWindowProc(hWnd, wMsg, wParam, lParam)),- 



// 

// DoCommand — process WM_COMMAND message for frame window by 

// decoding the menubar item with the menuitemsl] array, then 

// running the corresponding function to process the command. 



Figure 2: BADAPPX, the C-lan 



ce code for the BADAPP demonstration program. 
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2 of 2 



// 

LONG DoCommand (HWND hWnd. UINT wMsg, UINT wParam, LONG lparam) 
( 

int i; // scratch variable 

for(i = 0; i < dim(menui terns ) ; i++) // decode menu command and 

{ // run corresponding Eunction 

if (wParam == menuitems (i] .Code) 

retumt (*menuitems(i] .Fxn) (hwnd, wMsg, wParam, lparam)); 

) 

retum(DefwindowProc(hWnd, wMsg, wParam, lparam) ) ; 

) 

// 

// DODestroy — process WM_DESTROY message for frame window. 
// 

LONG DoDes troy ( HWND hWnd, UINT WMsg, UINT wParam, LONG lparam) 
( 

PostQuitMessage(0) ; // force WM_QUIT message to 

return (FALSE) ; // terminate the event loop 

) 

// 

// DoPaint -- process WM_PAINT message for frame window. Select 
//a pretty font, then display a message in the center of the window 
// to show that the program is alive. 

// 

LONG DoPaint (HVJND hWnd, UINT WMsg, UINT wParam, LONG lparam) 
I 

HDC hdc; 
PAINTSTRUCT ps; 
RECT rect; 
HFONT hfont; 

hdc = BeginPaint (hWnd, dps); // get device context 

GetclientRect thwnd, &rect> ; // get client area dimensions 

hfont = CreateFont(-36, 0, 0, 0, 700, TRUE. 0, 0, ANSI_CHARSET, 
OUT_DEFAULT_PRECIS . CLIP_DEFAULT_PRECIS , 
DEFAULT_QUALITY, (FF_MODERN « 4) + DEFAULT_P1TCH, 
•Ariel " ) i 

SelectObject (hdc, hfont); // select new font 

DrawText (hdc, "I'm Really Bad!", -1, // paint text in window 

irect, DT_CENTER | DT_VC ENTER | DT_SINGLELINE) ; 
Endpaint (hWnd, &ps) ; // release device context 

return (FALSE) ; 



// 

// DoMenuExit -- process File-Exit command from menu bar. 

// 

LONG DoMenuExit (HWND hWnd, UINT wMsg, UINT wParam, LONG lparam) 
( 

SendMessage (hWnd, WM_CLOSE. 0, 0L) ; // send window close message 
return(FALSE) ; // to shut down the app 

) 

// 

// DoMenuGPFault — process Gp Fault command from menu bar. Force 
//a fault by dereferencing a null pointer. 

// 



LONG DoMenuGPFault (HWND hWnd, UINT wMsg , UINT wParam, LONG lparam) 

1 

char c ; 

char far *p = NULL; 

c = "p; // dereference bogus pointer 

return (FALSE) ; // to force a GP fault 

) 

// 

// DoMenuHang — process Infinite Loop command from menu bar. 
// Execute an infinite loop until the user forces a local reboot 
// with Ctl-Alt-Del. 

// 

LONG DoMenuHang (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 

( 

while (TRUE) 
{ 

// execute practically forever 

) 

return (FALSE] ; 

) 

// 

// DoMenuZeroDiv -- process Divide by Zero command from menu bar. 
// Declare some integers, then force a divide by zero fault. 

// 

LONG DoMenuZeroDiv I HWND hWnd, UINT wMsg, UINT wParam, LONG lparam) 
{ 

int i, i. k = 0; 

i = j / k[ 
return (FALSE) ; 

) 

// 

// DoMenuBadHDC — process Bad HDC command from menu bar. Call the 
// DrawTextO API function with a bogus HDC. 

// 

LONG DoMenuBadHDC (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 

( 

HDC hdc = 0; 
RECT rect; 

GetclientRect (hwnd, &rect) ,- // get client area dimensions 

DrawText (hdc, "Bogus HDC!", -1, // use invalid HDC to paint text 

&rect. DT_CENTER j DT_VCENTER j DT_SINGLELINE) ; 
return (FALSE) ; 

) 

// 

// DoMenuBadPtr — process Bad Pointer command from menu bar. Call the 
// MessageBoxO API function with a NULL pointer to the message string. 

// 

LONG DoMenuBadPtr [HWND hwnd, UINT WMsg, UINT wParam, LONG lParam) 

MessageBox(hWnd, NULL, NULL, MB_OK [ MB_ICONSTOP) ; 
return(FALSE) ; 

) 



cation, or reset the machine entirely. 

How about the Pass Bad HDC menu 
item? The corresponding BADAPP rou- 
tine DoMenuBadHDC is implemented 
as a call to DrawText with a device con- 
text handle (HDC) of zero, and it appears 
to do nothing. The Windows developers 
apparently decided that this particular er- 
ror fell into the category where they 
could safely ignore the function call and 
allow the application to continue. After 
all, the worst that could happen is that 
the user wouldn't see something on the 
screen that ought to be there. If you are 
running the special debugging Windows 
kernel, however, you will get a warning 
message about the invalid handle on the 
debugging terminal. 

WORKING WITH TOOLHELP ToolHelp of- 
fers quite a diverse range of services, 



many of which we will be using in demon- 
stration programs in this column over the 
next few issues. Just to get our feet wet, 
however, let's try out ToolHelp's facili- 
ties for installing a notification callback 
routine for Windows API parameter er- 
rors. Whenever the application requests 
a Windows function with an invalid pa- 
rameter, Windows will (while the func- 
tion call is still in progress) call back into 
the notification routine with information 
about the error. This allows the applica- 
tion to decide what to do about its own 
error, but more important, allows the 
programmer to run the application under 
completely natural conditions — no de- 
bugger, no separate debugging terminal, 
no special Windows debugging kernel — 
and still gather information about this 
particular class of bugs. 



In order to use a notification callback 
routine in your own program, you must 
do the following: 

• Register an application-specific win- 
dow message in your application's in- 
stance initialization routine; this window 
message will be used by the notification 
callback routine to communicate with the 
body of your program. 

• Allocate a thunk for the callback rou- 
tine with MakeProcInstance() in the pro- 
gram's instance initialization routine. 

• Register the notification callback rou- 
tine with TOOLHELP.DLL by calling 
the function NotifyRegisterQ in the pro- 
gram's instance initialization routine. 

• Implement the notification callba^ 
routine itself. This entry must be declared 
as BOOL FAR PASCAL. It accepts an 
unsigned single integer and an unsigned 
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BADAPP2.C 

Complete Listing 



// BADAPP2 - Application Error Testbed for Windows 3.1 

// with Notification Callback 

// Copyright (C) 1992 Ray Duncan 

// Ziff Davis Publishing * PC Magazine 

#include "windows .h" 
#include " toolhelp.h" 
#include "badapp.h" 



WNDPROC lpNotifyCallback; 



// NotifyCallback thunk addr 



// Table of window messages supported by FrameWndProc ( ) 
// and the functions which correspond to each message. 

// 

struct decodeWord messages f] = { 
, DoNotif yMessage, 
WM_PAINT, DoPaint. 
WM_COMMAND , DoCommand, 
WH_DESTROY, DoDestroy, ) ; 



// These structures receive error information during ToolHelp callback. 



: nfylogerror; 
NFY LOG PARAMERROR nf ylogparamerror ; 



// Initlnstance 



stance initialization code for this application. 



BOOL InitInstance{HANDLE hlnstance, int nCmdShow] 



// allocate private message number for use by NotifyCallback 
messages[0] .Code = Regis terWindowMessage ( "BADAPP" ) ; 

// allocate thunk for callback then register it with ToolHelp.DLL 
lpNotifyCallback a MakeProcInstance ( (WNDPROCJNotifyCallback, hlnst) ; 
NotifyRegister(NULL, lpNotifyCallback, NF_NORMAL) ; 



return(TRUE) ; 



// Termlnstance 



// return success flag 



instance termination code for this application. 



BOOL Termlns tance ( HANDLE hinstance) 
{ 

NotifyUnRegister(NULL) ; // unregister ToolHelp callback 

FreeProcInstance(lpNotifyCallback) ,- // release callback 
return (TRUE) ; // return success flag 



// DoNotif yMessage -- process private message from NotifyCallback 

// 

LONG DoNotif yMessage (HWND hWnd, UINT wMsg, UINT wParam, LONG IParam) 
{ 

UINT i; 

char *p ; 

char temp [256] ; 

switch IwParam) 
{ 

case NFY_LOG ERROR : 

p = -NFY_LOGERROR' ; 

i = nfylogerror .wErrCode; 

break ; 

case NFY LOGPARAMERROR : 

p = " NFY_LOG PARAMERROR " ,- 

i = nf ylogparamerror. wErrCode, ■ 

break ,- 

default : 



// now format and display NotifyCallback information 

wsprintf (temp, "Notify type: %s\nError code: %04Xh", (LPSTR) p, i); 

MessageBox(hWnd, temp, "BadApp" , MB__OK j MB_ICONEXCLAMATION) ; 

return (FALSE) ; 



// NotifyCallback — callback routine for ToolHelp DLL. Looks for 
// codes indicating a parameter validation error in an API call, 
// saves information about the error, and posts a message to the 
// main message handling routine indicating that an error occurred. 

// 

BOOL FAR API ENTRY Notif yCal lback (UINT wID, LONG dwData) 



switch (wID) 



eter error 



case NFY_LOG ERROR : // API par 

nfylogerror = * (NFYLOGERROR far *) dwData; 

PostMessagefhFrame, messages[0] .Code, wID, 0) ; 

return (TRUE) ; // signal callback was handled 

case NFY_LOG PARAMERROR : // API parameter error 

nfylogparamerror = * (NFYLOG PARAMERROR far *) dwData; 
PostMessage(hFrame, messages (0] .Code, wID, 0) ,- 
retum(TRUE); // signal callback was handled 



default: 

return (FALSE) ; 



// signal callback not handled 



Figure 3: Extracts from BADAPP2.C, a modified version of BADAPP with notification callback handling. The full source code is available on PC MagNet. 



double integer as parameters; the single 
value is an error code and the double 
value is usually a far pointer to a structure 
that contains more information about the 
error. The callback routine is not allowed 
to do very much except call ToolHelp 
functions, make a copy of the error infor- 
mation in local static variables, and post 
a message to one of the application's win- 
dow handlers. 

• Add appropriate logic to one of the ap- 
plication's window handlers to process 
the message posted by the notification 

illback and take appropriate action (for 
sample, log the error to a disk file or 
display an alert dialog). 

• Modify the application's termination 
code to call the ToolHelp function 



NotifyUnRegister; this allows TOOL- 
HELP.DLL to deallocate those of its in- 
ternal data structures that are associated 
with the application. 

• Add static NFYLOGERROR or NFY- 
LOGPARAMERROR structures to the 
program; these can be used by the notifi- 
cation callback routine to make local cop- 
ies of the error information that is passed 
to it. 

• Export the notification callback routine 
in the application's module definition 
(.DEF) file. 

To illustrate these steps, I have modi- 
fied the BADAPP.C source code to cre- 
ate a new program, BADAPP2.C, which 
contains a notification callback. We 
could not print the entire listing, but ex- 



tracts of B AD APP2's source code, show- 
ing the portions that are specific to the 
handling of notification callbacks, can be 
found in Figure 3. As always, you can get 
the full source code and executable file 
for B ADAPP2.C by downloading it from 
PC MagNet, or by sending a postcard 
with your name and address to the atten- 
tion of Katherine West, PC Magazine, 
One Park Ave., New York, NY 10016; 
(no phone calls, please). 

THE IN-BOX Please send your ques- 
tions, comments, and suggestions to me 
at any of the following electronic mail ad- 
dresses: 

PC MagNet: 72241,52 
MCI Mail: rduncan 
BIX: rduncan □ 
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Married With childrea 



The traditional modem is a 
dying breed. And in its place comes a 
new generation of products. 

Introducing the Intel family of 
faxmodems — a combination of our 
award-winning modem technology 
and SatisFAXtions Board that brings 
you a no-compromise modem and fax 
in one. All for about the price of a data 
modem alone. 

Our top-of-the-line product, the 



SatisFAXtions Modem/400, 
is 50 percent faster than a 
traditional 9600bps modem. 
Plus it features unequalled 
fax capabilities. The Model 
400e is the powerful external 
brother to the Model 400. And Models 
200 and 100 are excellent values if you 
have less need for speed. 

So don't settle for just a modem. 
For the ultimate performance, features 



R'T.viiiiiia 



WORK 



Find out more. Ask for ext. 6 1 

1-800-538-3373 



and compatibility only 
Intel can give you, tie the 
faxmodem knot now. 

Experience our 
no-obligation, 14-day Test 
Drive program. For the 
Intel Test Drive dealer nearest you, 
call 1-800-538-3373, ext. 61. 



©I 992 Intel Corporation. SatisFAXiion is a registered trademark of Intel Corporation. For information faxed directly to you, 
call 1-80O-525-3O19 and ask for document 9898. For international inquiries, call 1-503-629-7354. In Europe, +44-793-431 155. 
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POWER PROGRAMMING 

The Windows 3 . 1 
ToolHelp DLL, Part 2 

BY RAY DUNCAN 



In the last column, I introduced you 
to Windows 3.1's TOOLHELP 
.DLL, a dynamic link library that 
gives you access to previously un- 
documented Windows data struc- 
tures and function calls. I had in- 
tended to continue in this issue with 
an example of how to trap General 
Protection (GP) Faults and other 
hardware exceptions using TOOL- 
HELP.DLL. But, to be frank, I couldn't 
get the code into a form that I considered 
publishable in time. ToolHelp's support 
f or interrupt handling is sufficient to de- 
/er control to your program's routines, 
but it's inadequate for clean handling of 
the interrupt. Furthermore, the Tool- 
Help support is not structured so that you 
can easily write the entire interrupt han- 
dler in a high-level language. I can get the 
stuff to work, but my current solution just 
isn't aesthetically appealing. 

So I'll let my subconscious work on the 
ToolHelp interrupt-handler problem for 
awhile, and look at a different topic this 
time: the ToolHelp API for inspecting 
and enumerating the system module list, 
task list, window classes, and global heap. 
If you're an experienced Windows pro- 
grammer, this API will be a pleasant sur- 
prise: It's predictable, symmetric, and 
easy to use; the function names actually 
make some kind of sense; and it's power- 
ful enough for the needs of just about any 
system-spelunking application. 

THE SYSTEM VOYEUR API I think of the 
ToolHelp functions related to the task 
list, module list, window class list, and 
global heap as "voyeur" functions be- 
cause they let you peek at, but not touch, 
e corresponding Windows internal data 
ocructures. Actually, you don't even get 
a direct look at the structures — you get 
a transformed and somewhat massaged 



reflection of the actual data, copied into 
data structures that lie in your applica- 
tion's own address space. The functions 
fall into two categories (as shown in Fig- 
ure 1): those that let you "walk" through 
one of the system's linked lists of data ob- 
jects, and those that let you retrieve infor- 
mation about a specific data object using 
a handle or name. 

All of the ToolHelp voyeur functions 

A sample program 
demonstrates the ToolHelp 
API for inspecting 
the system module 
list, task list, window 
classes, and global heap. 



are used in essentially the same way. 
First, you allocate a data structure spe- 
cific to the type of information being re- 
trieved: task, module, window class, or 
global heap block. Next, you enter the 
function via a far call, passing a far 
pointer to the data structure and — if 
you're retrieving information about a 
particular object rather than walking a 
list — an additional flag, handle, or string 
pointer. All of the functions return a 
TRUE value if successful and a FALSE 
value if they fail or encounter an error; 
other information, if any, is placed in the 
data structure whose address was passed 
in the original call. 

To make this more concrete, let's see 
how we would enumerate all the active 
tasks in the system. We need a data struc- 
ture called TASKENTRY and two API 



functions: TaskFirst() and TaskNext(). 
The data structure must be initialized be- 
fore use, and the first field of the structure 
contains the length of the structure, 
which is used as a sanity check by Win- 
dows. The skeleton for a loop that walked 
the task list would look like this: 

// allocate the data structure 
TASKENTRY fee; 

//initialize the data structure 
memset (&te, 0, sizeof (TASKENTRY) ; 
te.dwSize = sizeof (TASKENTRY) ; 

// now walk the task list 
TaskFirst (&te) 

do { 

// process results in 
// structure "te" here 
} while (TaskNext (&te) ) ; 

Notice that we don't have to worry about 
the success of the TaskFirst() call because 
we know that at least one task will always 
be running: our own program! The func- 
tions for walking the module, window, 
and global heap lists are used in an almost 
identical fashion. 

Now suppose we want to retrieve the 
information about a specific task directly, 
rather than walking the task list until we 
run into it (or not). Assuming we have 
the task's handle to work with, we can 
use the TaskFindHandleQ function to- 
gether with the familiar TASKENTRY 
data structure: 

// task info data structure 
TASKENTRY te; 

// handle of task to find 
HTASK htask; 
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//initialize the data structure 
memset(&te, 0, sizeof (TASKENTRY) ; 
te.dwSize = sizeof (TASKENTRY) ; 

// now retrieve task info 

if (TaskFindHandle (&te, htask) ) 

// function was successful 
else 

// an error occurred 

The API functions for retrieving infor- 
mation about a specific module, class, or 
global heap block work in much the same 
way (allowing for the data object-specific 
structures, of course). The functions for 
the different data object types can also 
be used in combination; for example, as 
you walk down the task list, you can use 
the module handle returned for a task in 
the TASKENTRY structure together 
with the ModuleFindHandleQ function 
to fetch the task's ASCIIZ modulename 
and pathname. Similarly, when walking 
the global heap, you can use the owner 
handle returned in the GLOBAL- 
ENTRY structure for a particular mem- 
ory block together with the TaskFind- 
Handle() and ModuleFindHandle() 
functions to find the task or module name 
of the block's owner. 

THE SYSMON PROGRAM With the ad- 
vent of TOOLHELP.DLL, the creation 
of programs that used to require weeks 
of painful experimentation and debug- 
ging is now easy and even fun. For this 
issue, I've written a simple system moni- 
tor utility called SYSMON that lets you 
display all of the system lists we've dis- 
cussed: tasks, modules, window classes, 
and the global heap. The C-language 
source code for SYSMON is listed in Fig- 





The ToolHelp Voyeur Functions 


Information type 


Walk API 


Specific object API 


Data structure 


Window classes ClassFirstO 


GetClasslnfoO 


CLASSENTRY 


ClassNextl) 


Active modules 


ModuleFirst() 


ModuleFindHandleO 


MODULEENTRY 




ModuleNextO 


ModuleFindNameO 




Active tasks 


TaskFirstO 


TaskFindHandleO 


TASKENTRY 


TaskNextO 


Global heap 


GlobalFir'stO 


GloballnfoO 


GLOBALENTRY 




GlobalNextO 


GlobalEntryHandleO 




GlobalEntryModuleO 



Figure 1: These functions fall into two categories: those that allow you to "walk" 
through one of the system's linked lists of data objects, and those that let you 
retrieve information about a specific data object. 
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ure 2, and the complete set of files neces- 
sary to build the application, along with 
the executable file, can be downloaded 
from PC MagNet, archived as SYS- 
MON.ZIP. 

From the user's point of view, SYS- 
MON is just a resizeable window contain- 
ing scrollable text, with three choices 
available on the menu bar. The first two 
menu bar items are pop-ups: the File 
menu, which lets the user activate the 
About. . . dialog box or exit the applica- 
tion; and the Display menu, which allows 
the user to select a display of the task list, 
module list, window class list, or global 
heap. (Users with really big screens also 
have the option of loading four different 
copies of the program at the same time 
and having each one display different in- 
formation.) The third menu item is Re- 
fresh!, which simply forces the program 
to rewalk the currently selected system 
list and rebuild its output. The observant 
user will note that SYSMON also auto- 
matically refreshes its display every 10 
seconds when it doesn't have the input 
focus, and that it "remembers" its most 
recent window size and position from one 
invocation to the next. The screen shot 
in Figure 3 shows SYSMON in action. 

At the source-code level, SYSMON is 
based on the same table-driven approach 
to message handling that I showed in the 
DLGDEMO and BADAPP programs. 
This scheme facilitates the use of short, 
reusable routines rather than the lengthy, 
convoluted case statements generally 
found in Windows programming books, 
and I've found that it significantly short- 
ens and simplifies both the coding and de- 
bugging phases of writing a new Windows 
application. 
When you want 
to expand a pro- 
gram with code 
that handles an 
additional mes- 
sage, you simply 
write a short rou- 
tine for that spe- 
cific message, 
add the routine's 
address and the 
message identi- 
fier to the master 
message handler 
table, and stick 
another proto- 



type into the application's header file. 
The previously existing (and presumabl 
correct) application source code does not 
need to be changed at all. 

As far as the ToolHelp aspects of SYS- 
MON are concerned, the four routines to 
study are WalkClassList(), WalkTask- 
List(), WalkModuleList(), and WalkGlo- 
balHeap(). These illustrate calls to the 
xxxFirstO and xxxNext() functions listed 
in Figure 1, along with their respective 
data structures. In order to keep the code 
in these functions easy to understand, 
I've kept the processing of the data struc- 
tures rather simple, but you can quickly 
enhance the functions to format the in- 
formation in the data structures more 
completely and more elaborately. 

Aside from its interface with 
TOOLHELP.DLL, SYSMON's source 
code has several other interesting fea- 
tures you may wish to incorporate into 
your own programs. The first is SYS- 
MON's capability to recall where it was 
last located on the screen. This feature 
turns out to be quite easy to implement, 
considering the huge difference in friend- 
liness it projects to the user. You just usp 
the functions GetWindowRect() an> 
WritePrivateProfileStringO to determine 
the window coordinates at application 
termination time and write them into an 
application-specific .INI file, then use 
GetPrivateProfileInt() and MoveWin- 
dow() to retrieve the coordinates from 
the .INI file and size and position the win- 
dow at application initialization time. 
The SYSMON source code that handles 
this can be found in the routines Update- 
Profile() and Initlnstance(), respectively. 

The next feature that is especially 
worth mentioning is the periodic refresh 
of the display, which is also easy to imple- 
ment. A thunk for the timer callback 
function is allocated in InitlnstanceQ 
with a call to MakeProcInstanceQ, and 
then a Windows system timer is activated 
and its interval specified with a call to Set- 
TimerQ. Windows subsequently enters 
the timer callback function, named 
TimerProc(), at 10-second intervals — 
irrespective of what other application 
might be in the foreground. The callback 
function first checks whether SYSMON's 
window is iconized or has the input focu- 
if neither condition is the case, the call- 
back function just calls SendMessage() to 
send an IDM_REFRESH message to 
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SYSMON.C 

1 of 4. 



// SysMon - System Monitor for Windows 3.1 

// Copyright (C) 1992 Ray Duncan 

// PC Magazine * Ziff Davis Publishing 

#define dim{x) (sizeof(x) / sizeof (x[0] ) ) 
#define MAXLINES 4096 

#include "stdlib.h" 
#include "windows .h" 
# include " toolhelp .h" 
# include " sysmon . h" 



// returns no. of elements 
// max lines to display 



HANDLE hlnst; 
HWND hFrame; 
HFONT hFont; 

int CharX, CharY; 

int LinesPerPage; 

int CurLine = 0; 

int TotLines = 0; 

int TopLine = 0; 

int DisplayType = I DM_MO DU L E ; 

char *LinePtr (MAXLINES] ; 

char szFrameClass ( ] = "SysMon"; 
char szAppNamef] = "System Monitor" 
char szMenuName [ ] = " SysMonMenu " ; 
char szlni[] = "sysmon.ini"; 

WNDPROC lpTimerProc; 



// module instance handle 

// handle for frame window 

// handle for nonprop. font 

// character dimensions 

// lines per page 

// first line, current page 

// total lines to display 

// first line of last page 

// type of info to display 

// holds pointers to lines 



// classname for frame window 

// long application name 

// name of menu resource 

// name of private INI file 

// timer callback thunk 



// Table of window messages supported by FrameWndProc ( ) 
// and the functions which correspond to each message. 

// 

struct decodeWord frameMsgs[] = { 
WM^PAINT, DoPaint, 
WM_SIZE, DoSize, 
WM_COMMAND, DoCommand, 
WM_CLOSE, DoClose, 
WM_DESTROY , DoDes troy , 
WM_VSCROLL, DoVScroll, } ; 

// 

// Table of menubar item IDs and their corresponding functions. 
// 

struct decodeWord menuitemsf] = ( 
IDM_EXIT, DoMenuExit, 
IDM_ABOUT , DoMenuAbout , 
IDM_MODULE, DoDisplayType , 
IDM_CLASS, DoDisplayType, 
IDM_TASK, DoDisplayType , 
IDM_HEAP, DoDisplayType , 
IDM_REFRESH, DoRefresh, } ; 

// 

// WinMain — entry point for this application from Windows. 

// 

int API ENTRY WinMain (HANDLE hlnstance, 

HANDLE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) 



MSG msg; 

hlnst = hlnstance; 



// scratch message storage 
// save this instance handle 



// if first instance, 

/ / register window class 



if { IhPrevInstance) 

if ( ! In it App (hlnstance) ) 
{ 

MessageBox (hFrame, "Can't initialize SysMon!", szAppName, 

MB_ICONSTOP j MB_OK) ; 
return(FALSE) ; 

) 

if ( ! Initlnstancefhlnstance, nCmdShow) ) // create this instance's window 
{ 

MessageBox(hFrame, "Can't initialize SysMon!", szAppName, 

MB_IC0NSTOP j MB_OK) ; 
return(FALSE) ; 



) 



while(GetMessage(&msg, NULL , 0, 0)) 
{ 

TranslateMessage f&msg) ; 
DispatchMessage (&msg) ; 

} 

Termlnstance (hlnstance) ; 
return(msg.wParam) ; 



// while message != WM_QUIT 

// translate virtual key codes 
// dispatch message to window 



// clean up for this instance 
// return code = WM_QUIT value 



// 

// InitApp global initialization code for this applicatio: 

// 

BOOL InitApp (HANDLE hlnstance) 
{ 

wc; 



indow class info 



/ / at>t pflrameters fcr frano wind 



WC. style = CS_HREDRAW j CS__VREDRAW; 
wc . lpf nWndProc = FrameWndProc; 
wc . cbClsExtra = 0; 
wc . cbWndExtra = 0; 
wc. hlnstance = hlnstance; 
wc.hlcon = Loadlcon (hlnst , "SysMonlcon" ) 
wc.hCursor = LoadCursor (NULL, IDC_ARR0W) 
wc . hbrBackground = GetStockObject (WHITE, 
wc . IpszMenuName = szMenuName ,- 
wc. IpszClassName = szFrameClass; 



return (RegisterClass (&wc) ) ; 



// class style 
// class callback function 
// extra per-class data 
// extra per -window data 
// handle of class owner 

// application icon 
// default cursor 
BRUSH); // background color 
/ / name of menu resource 
// name of window class 

// register frame window class 



// Initlnstance instance initialization code for this application. 

// 

BOOL initlnstance (HANDLE hlnstance, int nCmdShow) 



HDC hdc; 

TEXTMETRIC tin; 
RECT rect; 
int i; 

for(i = 0; i < MAXLINES; i++) 
LinePtrfi] = NULL; 

hFrame = CreateWindow ( 
szFrameClass, 



// handle for device context 

// info about font 

// window position & size 

/ / scratch variable 



// 

// : 



alize all lin 



WS_OVERLAPPEDWINDOW [ WS_VSCROLL, 
CW_USEDEFAULT, CWJJSEDEFAULT, 
CW_USEDE FAULT , CW_USEDEFAULT, 
NULL , 

NULL, 

hlnstance, 
NULL) ; 

if ( IhFrame) return(FALSE) ; 



/ / create frame window 

// window class name 

// text for title bar 

// window style 

// default position 

// default size 

//no parent window 

// use class default menu 

/ / window owner 

// unused pointer 

// error, can't create window 



// get device context 



hdc = GetDC (hFrame) ; 
hFont = GetStockObject (SYSTEM_FIXED__FONT) ; // handle for nonprop. font 
SelectObject(hdc, hFont); // realize the font and get 

GetTextMetrics (hdc, &tm) ; // the character dimensions 

CharX = tm. tmAveCharWidth; 

CharY = tm.tmHeight + tm. tmExternalLeading; 

ReleaseDC (hFrame, hdc); // release device context 



GetWindowRect (hFrame, &rect} ; 



// current window pos & 



// read profile for frame window from previous invocation, if any 
rect . left = GetPrivateProf ilelnt ( "Frame" , "xul " , rect . left , szlni ) ; 
rect . top * GetPrivateProf ilelnt ( "Frame" , "yul" , rect . top, szlni ) ; 
rect . right = GetPrivateProf ilelnt ( "Frame" , "xlr " , rect . right, szlni ) ; 
rect -bottom = GetPrivateProf ilelnt ( "Frame" , "ylr" , rect .bottom, szlni ) ; 

MoveWindowfhFrame, rect. left, rect. top, // force window size & position 
rect . right -rect . left, rect . bottom-rect . top, TRUE) ; 



// get display type from previous invocation, default to module list 
DisplayType = GetPrivateProf ilelnt ( "Frame" , "type", I DM_MO DU L E , szlni) ; 

ShowWindow(hFrame, nCmdShow) ; // make frame window visible 

UpdateWindow (hFrame ) ,- // force WM_PAINT message 

SendMessagefhFrame, WM_COMMAND, DisplayType, 0); // initialize display 

// allocate thunk for timer callback routine 

lpTimerProc = Make Pro c Instance ( (WNDPROC) TimerProc, hlnst) ; 

// set up our 10 sec. (10,000 msec) timer callback 
if ( !SetTimer(hFrame, 1, 10000, lpTimerProc)) 
return(FALSE) ; 



return (TRUE) ; 



// return success flag 



// Termlnstance -- instance termination code for this application. 

// Does nothing in this case, included for symmetry with Initlnstance. 



BOOL Termlnstance (HANDLE hlnstance) 
{ 

return (TRUE) ; 



// return success flag 



// FrameWndProc callback function for application frame window. 

// Searches frameMsgs[] for message match, runs corresponding function. 

// 

LONG FAR API ENTRY FrameWndProc ( HWND hWnd, UINT wMsg, UINT wParam, LONG iParam) 

{ 

int i; // scratch variable 

for(i =0; i < dim(frameMsgs) ; i++) // decode window message and 

{ // run corresponding function 

iffwMsg == frameMsgs [i] .Code) 

return! ( * f rameMsgs [i] -Fxn) (hWnd, wMsg, wParam, IParam) ) ; 

) 



Figure 2: Here is the source code for the System Monitor utility. 



SEPTEMBER 15, 1992 PC MAGAZINE 451 



SY5MUN.U 

2 of 4 



return ( DefWindowProc IhWnd, wMsg, wParam, lParair.) ) ; 



// DoCommand process WM_C OMMAND message for frame window by 
// decoding Che menubar item with the menuitems[] array, then 
// running the corresponding function to process the command. 

n 

LONG DoCommand (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 
{ 

int i; // scratch variable 

for(i = 0; i < dim(menuitems) ; i++) // decode menu command and 

{ // run corresponding functi< 

if (wParam == menuitems [ i ] .Code) 

return( ( *menui terns [ i ] .Fxn) (hWnd, wMsg, wParam, lParam) ) j 

} 

return (DefWindowProc (hWnd, wMsg, wParam, lParam)); 



// DoDestroy — process WM_DESTROY message for frame window. 

// 

LONG DoDestroy (HWND hWnd, UINT WMsg, UINT wParam, LONG lParam) 



PostQuitMessage{0) ; 
return! 0) ; 



/ / force WM_QUIT message to 
// terminate the event loop 



// DoClose -- process WM_CLOSE message for frame window. 

// 

LONG DoClose (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 



UpdateProf ile I ) j 
DestroyWindow(hWnd) ; 
return (FALSE) ; 



// save window size & positi 
// then close down app 



// DoVScroll process WM_VSCROLL message for frame window. 

// 

LONG DoVScroll (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 
{ 

RECT rect; 



switch (LOWORD (wParam) ) 



case SB_TOP: 

if (CurLine) 



// LOWORD vital for Win32 



// go to top of output if 
// we aren't there already 



SetCurLine ( ) ; 
Repaint ( ) ; 



case SB_BOTTOM: 

if (CurLine < TopLine) 
{ 

SetCurLine(TopLine) ; 
Repaint ( } ; 

} 

break : 

case SB_LINEUP: 
if (CurLine) 
{ 

SetCurLine (CurLine - 1); 

ScrollWindowlhWnd, 0, CharY, NULL , NULL) ; 
UpdateWindow(hWnd) * 

} 

break ; 



// go to bottom of output if 
// we aren't there already 



// scroll up by one line if 
// we aren't already at top 



// scroll down by one line if 
// we aren't already at bottom 



case S B_L I NEDOWN : 

if (CurLine < TopLine) 
{ 

SetCurLine (CurLine +1); 

ScrollWindowlhWnd, 0, -CharY, NULL, NULL) ; 
GetClientRect (hWnd, Srect); 

rect. top = max(0, (LinesPerPage-1) * CharY); 
Ir.validateRect{hWnd, Street, TRUE); 
UpdateWindow (hWnd) ; 

} 

break ; 

case SB_PAGEUP: // scroll up by one page 

SetCurLine (CurLine - LinesPerPage); 
Repaint t ) ; 
break ,- 

case SB_PAGEDOWN: // scroll down by one page 

SetCurLine(CurLine + LinesPerPage); 
Repaint ( J ; 
break j 



case SB_THUMBPOSITION: 



// scroll display accordina 



SetCurLine (THUMBPOS) ; 

Repaint ( ) ; 

break; 



// to new thumb position 



return (FALSE) ; 



// DoPaint -- process WM„PAINT message for frame window. 

// 

LONG DoPaint (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 

HDC fide; 
PAINTSTRUCT pS; 
int i; 



hdc = BeginPaint (hWnd, &ps) ,- 
SelectObject (hdc, hFont) ; 



for(i = 0; i < LinesPerPage; i++) 
PaintLine(hdc, i) ; 



EndPaint (hWnd, &ps) ; 
return(FALSE) ; 



// get device context 
// select non-prop, font 



// paint lines of text 
//in the window 



// release device context 



// DoSize -- process WM_SIZE message for frame window. 

// 

LONG DOS i ze ( HWND hWnd, UINT wMsg, UINT WParam, LONG lParam) 

{ 

LinesPerPage = HIWORD ( lParam) / CharY; // window height / char height 
Conf igWindow( ) ; // calc display parameters 

if (CurLine > TopLine) // make sure window refilled 

SetCurLine (TopLine) ; // if window got bigger 

return (0) ; 



// DoMenuExit -- process File-Exit command from menu bar. 

// 

LONG DoMenuExit [HWND hWnd, UINT WMsg, UINT wParam, LONG lParam) 



SendMessage (hWnd, WM_CLOSE, 0, 0L) ; // send window close message 
return(FALSE) ; // to shut down the app 



// DoDisplayType -- process items on Display popup to select 

// the type of information to display, then force window update 



LONG DoDisplayType (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 



HHENU hMenu; 



// scratch menu handle 



hMenu = GetMenu (hWnd) ; // update popup checkmark 

CheckMenultem(hMenu. DisplayType, MF_UNCHECKED) j 
DisplayType = wParam; 

CheckMenuItem(hMenu, DisplayType, MF_CHECKED) ; 

SendMessage (hWnd, WM_COMMAND, IDM_REFRESH, 0); // update window 

return (FALSE) ; 



// DoRefresh -- rebuild the information for display according to 
// the currently selected display type, then refresh the window. 

// 

LONG DoRefresh (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 

{ 

EmptyLines ( ) ; // discard previous output 



switch (DisplayType) 

{ 

case IDM_MODULE: 

WalkModuleListO ; 
SetWindowCapt ion ( "Modules" 
break ; 



case IDM_CLASS: 

WalkClassList () ; 

SetWindowCapt ion ( "Window Classes*) ; 
break; 

case IDM_TASK: 

WalkTaskList ( ) ; 

SetWindowCaption | "Active Tasks") ; 
break; 

case IDM_HEAP: 

WalkGlobalHeapO j 
SetWindowCaption ( 'Global Heap"),- 
break; 



// call the appropriate 
// list walking routine 
// according to display type 



Conf igWindowf ) ; 
Repaint ( ) ; 



// configure scroll bar etc. 
// refresh the window 
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// DoMenuAbout — process File- About command from menu bar. 
// 

LONG DoMenuAbout ( HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 



WNDPROC lpAboutProc; 



// scratch far pointer 



// allocate a thunk for the dialog callback, then display dialog 
lpAboutProc = MakeProcInstance ( (WNDPROC ) AboutDlgProc , hlnst) ,- 
DialogBox (hlnst , "AboutBox" , hWnd, lpAboutProc) ; 
FreeProcInstance ( lpAboutProc) ; 
return(FALSE) ,- 



// 

// AboutDlgProc — callback routine for About... dialog. Basically 

// ignores all messages except for the OK button, which dismisses dialog. 

// 

BOOL FAR API ENTRY AboutDlgProc (HWND hwnd, UINT msg, UINT wParam, LONG lParam) 



if ((msg == WM_COMMAND) && {wParam == IDOK) ) 

EndDialog(hwnd, 0) ; // if OK button, destroy dialog 

else return (FALSE) ; // otherwise ignore message 



// WalkModuleList -- uses ToolHelp functions to walk through 
// module list and build formatted output in LinePtr[] array. 



VOID WalkModuleList (VOID) 



MODULEENTRY me; 
char temp[256] ; 



// receives module info 

// scratch formatting buffer 



memset (&me, 0, sizeof (MODULEENTRY) ) ; // initialize structure for 
me.dwSize = sizeof (MODULEENTRY) ; // return of module data 

AddLine ( "Handle Usage Module Pathname" } ; / / format title 
ModuleFirst l&me) ; // initialize to 1st module 



do { 

wsprintf (temp, "%04Xh 

(LPSTR) me.szModule, 
AddLine (temp) ; 
) while (ModuleNext (&me) ) ; 



// format module information 
S4d %-8.8s %s", me.hModule, me.wcUsage, 
(LPSTR) me.szExePath) ; 

// add to array for output 
// get next module name 



// WalkClassList — uses ToolHelp functions to walk through 

// window class list and build formatted output in LinePtrU array. 

// 

VOID WalkClassList (VOID) 
{ 

C LAS SENTRY ce; 
char tempI256] ,- 

memset (dee, 0, sizeof (CLASSENTRY) ) ; 
ce.dwSize ± sizeof (CLASSENTRY) ; 
AddLine ( "Owner Class Name"); 
ClassFirst (ice) ; 



receives window class info 
scratch formatting buffer 



// initialize structure for 
// return of window class data 
// format title 
// initialize to 1st class 



do ( 

wsprintf ( temp, "%04J1 
AddLine (temp) ; 
} while (ClassNext (&ce) ) ; 



// format owner & classname 

ce. hlnst, (LPSTR) ce.szClassName) ; 

// add to array for output 

// get next class name 



// WalkTaskList — uses ToolHelp functions to walk through 
// task list and build formatted output in LinePtrU array. 

// 

VOID WalkTaskList (VOID) 
{ 

TASKENTRY te; 
MODULE ENTRY me; 
char temp[256] ; 

memset (&te, 0, sizeof (TASKENTRY) ) ; 
te.dwSize * sizeof (TASKENTRY) ; 
memset(&me, 0, sizeof (MODULEENTRY) ) j 
me.dwSize = sizeof (MODULEENTRY) ; 
AddLinef "Task Parent Instance 

AddLine { "Handle Task Handle 
TaskFirst (&te) ; 



// receives task info 
/ / receives module info 
// scratch formatting buffer 

// initialize structure for 
// return of task info 
// initialize structure for 
// return of module data 
Module Module Module" ) ; 

Handle Name Pathname") ; 

// initialize to 1st task 



do { // format task information 

ModuleFindHandle (&me, te.hModule); // get modulename & pathname 
wsprintf (temp, -%04Xh %04Xh %04Xh %04Xh %-8 . 8s %s 

te.hTask, te.hTaskParent, te. hlnst, te.hModule, 
(LPSTR) me.szModule, (LPSTR) me . szExePath ) ,- 
AddLine (temp) ; // add to array for output 

) while(TaskNext(&te) ) ; // get next task 



// WalkGlobalHeap — uses ToolHelp functions to walk through 
// global heap and build formatted output in LinePtrU array. 



VOID WalkGlobalHeap (VOID) 

{ 

GLOBAL ENTRY ge; 
TASKENTRY te; 
MODULEENTRY me; 
char temp [256] ; 

memsetlfcge, 0, sizeof (GLOBALENTRY) ) ; 
ge.dwSize = sizeof (GLOBALENTRY) ; 
memset (&me, 0, sizeof (MODULEENTRY) ) ; 
me.dwSize 5? sizeof (MODULEENTRY) ; 
memset(&te, 0, sizeof (TASKENTRY) ) ; 
te.dwSize = sizeof (TASKENTRY) ; 
AddLine ("Handle Linear Addr Siz 
GlobalFirst(&ge, GLOBAL_ALL) ; 



{ 



// receives heap block info 

// receives task info 

// receives module info 

// scratch formatting buffer 

// initialize structure for 
// return of heap block info 
II initialize structure for 
// return of module data 
// initialize structure for 
// return of task info 

Type Owner"); // format title 
// initialize to 1st block 

fj format heap block info 
// get owner's name 



if (TaskFindHandlef&te, ge.hOwner) ) 

ModuleFindHandle (&me, te.hModule) ; 
else if ( !ModuleFindHandle(&me, ge.hOwner) ) 

me.szModule[0] = '\0'; 
wsprintf (temp, "%04Xh %081Xh %091Xh %04Xh %04Xh%s", 

ge . hBlock , ge . dwAddress , ge . dwBlockSi ze , ge . wType , 

ge.hOwner, (LPSTR) me.szModule) ; 
AddLine ( temp) ; // add to array for output 

} while(GlobalNext(&ge, GLOBAL_ALL) ) ; // get next class name 



// 

// SetCurLine 
// the range (( 
// 

VOID SetCurLine (int NewLine) 
{ 

CurLine = min (max (NewLine, 0) 
SetScrollPos(hFrame, SB_VERT, 

J 



called to set CurLine to valid value, clamped to 
. ..TopLine), and redraw thumb on scroll bar. 



TopLine) ; 
CurLine, TRUE) ; 



// ConfigWindow — Configures various display parameters and scrollbar 
// according to total lines of output, current window size, and the 
// number of lines that will fit into the window. 

// 

VOID ConfigWindow(VOID) 
{ 

// calc line number of first line of last page 
TopLine = max(TotLines - LinesPerPage, 0) ; 

// update scroll bar range and thumb position 
SetScrollRange(hFrame, SB_ VERT , 0, TopLine, FALSE); 
SetScrollPos(hFrame, SB_VERT , CurLine, TRUE) ; 



// 

// AddLine -- called with a pointer to an ASCIIZ string, allocates 
ft memory from the heap to hold the string, puts the pointer 
// to the heap block into the next position in the LinePtrf] array, 
II and updates the total line count. 

// 

VOID AddLine (char * p) 
{ 

char * q; 



if(TotLines == MAXLINES) 

return ; 
q = malloc (strlen (p) +1) ; 
if (q == 0) 

return; 
strcpy (q, p) j 
LinePtr [TotLines] = q; 
TotLines++; 



fj scratch pointer 

II bail out if line pointer 

// array is already full 

// allocate memory for line 

// bail out out if no 

// heap space available 

// copy string to heap 

// put heap pointer into array 

// count lines of output 



'// EmptyLines - releases all heap blocks in LinePtr [] array, 
// then zeros out the line pointers and the total line count 



VOID EmptyLines (VOID) 



for(i 
{ 



MAXLINES; i++) 



if (LinePtrfi] ) 



free(LinePtr[i] ) ; 
LinePtr[i] = NULL; 



CurLine = 0; 
TotLines = 0; 
TopLine = 0; 



// scratch variable 



// if this position in 
// the LinePtr array is 
// nonzero, release the 
// heap block, then zero 
/ / out the LinePtr slot 



// initialize various 

// other global variables 



// PaintLine — paint a single line of text in the window. 
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// The passed line number is relative to the window, NOT to the 
// total array of formatted output available to be painted. 



e(HDC hdc, INT RelLine) 

RelLine + CurLine; 
[Line] ) 

(hdc, 0. RelLine *CharY, LinePtr [Line] , scrlen (LinePtr [Line) ) ) ,- 



// Repaint - force repaint of all formatted output in main window 



// 

VOID Repaint (VOID) 
{ 

InvalidateRect (hFrame, NULL, TRUE); 

} 




// force repaint entire window 



// 

// SetWindowCaption — concatenate the application name with the 
// display type, then update the frame window's title bar. 

// 

VOID SetWindowCaption (char * szDisplayType) 

{ 

char szTemp[256] ; // scratch buffer 



strcpy(szTemp, szAppName) j 



, szDisplayType); 
(hFrame , szTemp) ; 




// get application name 

// add separator 

// add information type 

// put result into title bar 



let) — saves the current window size and position 
type in the application's private INI file. 



RECT rect; 
char temp [20] 



if (Islconic (hFrame) ) ( IsZoomed (hFrame) ) return; 
GetWindowRect (hFrame , &rect ) ; 



wsprintf ( temp, "%d" , rect .left) j 
WritePrivateProf ileString( "Frame " 



wsprintf ( temp, "%d" , rect . top) ; 
WritePrivateProf ileString ( "Frame" 



wsprintf £ temp, "%d" , rect . right ) ; 
WritePrivateProf ileString ( " Frame" 



wsprintf { temp, "%d" , rect .bottom) ; 
WritePrivateProf ileString ( "Frame" 



wsprintf (temp, "%d" , DisplayType) ; 
WritePrivateProf ileString ( "Frame" 



"xul", temp, szlni); 
"yul", temp, szlni) ; 
"xlr' , temp, szlni) ; 
"ylr" , temp, szlni); 
"type", temp, szlni) ; 



// TimerProcO — Callback for 10 second timer. Refresh display 
// if window is not minimized and does not have the focus. 

// 

WORD FAR API ENTRY TimerProc (HWND hwnd, WORD message, WORD wParam, LONG lParam) 



if ( ( ilsIconic(hFrame) ) && (hFrame != GetFocusI))) 

SendMessage (hFrame, WH_COMMAND, IDM_REFRESH, 0) ; 
return (FALSE) ; 



SYSMON's frame window — and the 
message is handled exactly as though the 
user had clicked the Refresh! item on the 
menu bar. This is a potent example of 
how exploitation of Windows' event- 
driven, message-based architecture can 
simplify application design. 

The third (and perhaps most novel) 
characteristic of SYSMON's source code 
I'd like to bring to your attention is the 
handling of the text displayed in the main 
window. If you try to integrate the paint- 
ing of text and the control of the scroll- 
bar's range and thumb position with the 
code that actually walks the system lists, 
you get a real mess. There's no way to 
predict how many items will be found in 
a list in advance, and this may change 





Nodule Pathname 

KERNEL C:\WIND0WS\SVSTEH\KftNL386.EXE 

SVSTEN C:\UINDOVK\SVSTEN\SVSTEN.DRU 

KEYBOARD C:\U1NDDUS\SVSTEM\KEYB0flRD.DRU 

HOUSE C:\WIND0WS\SVSTEN\MOUSE.DRU 

DISPLflV C:\WINDOWS\SVSTEM\UGn-DRU 

SOUND C:\WINDDWS\SVSTEM\MMSOUNO.DRU 

CONN C:\WINDOWS\SVSTEM\C0MM.DRU 

FONTS C:\WINDOWS\SVSTEM\oCftSVS .FON 



Figure 3: The SYSMON utility, with the task list display selected. 



from one walk of the list to another, mak- 
ing scrolling the display backwards and 
forwards and maintenance of the scroll- 
bar itself a messy proposition. The solu- 
tion is to completely divorce the code that 
generates the text to be displayed from 
the code that actually paints the text in 
the window. The two bodies of code com- 
municate via an array of pointers called 
LinePtrs[]. Each slot in LinePtrs[] corre- 
sponds to a line of text to be displayed 
and either contains a pointer to an 
ASCIIZ string or a NULL pointer if the 
line is empty. 

The central routines that format infor- 
mation for display — that is, the four rou- 
tines WalkClassList(), WalkTaskList(), 
WalkModuleList(), and WalkGlobal- 
Heap() — initialize the display 
(from their point of view) by 
calling EmptyLines(), and 
place text on the display by re- 
peatedly calling AddLine(). 
But what EmptyLines() actu- 
ally does is just zero out Line- 
Ptrs[] and the count of the lines 
to be displayed, while Add- 
Line() merely allocates some 
heap space to hold the string 
that is passed to it, puts a 
pointer to the heap block into 
LinePtrs[], and increments the 
line count. After a list-walking 




routine is done with its work, it calls 
ConfigWindow(), which calculates the 
line number of the first line in the last 
display page (if there is enough text tha 
scrolling will be required) and configures 
or hides the scrollbar. 

Which routine takes text out of Line- 
Ptrs[] and paints it in the SYSMON win- 
dow? Why, DoPaint(), naturally, which 
is called whenever the application re- 
ceives a WM_PAINT message. Do- 
Paint() can behave as though the con- 
tents of LinePtrs[] are static, and it gets 
the total number of lines of text from the 
variable TotLines, the number of the first 
line to be displayed in the window from 
the variable CurLine, and the number of 
lines that the window can hold from the 
variable LinesPerPage. The message- 
handler routine for scrollbar messages, 
DoVScroll(), needs to do little more than 
manipulate the variable CurLine and 
send a WM_PAINT message to the SYS- 
MON window. At that point, the display 
logic degenerates to mindless bookkeep- 
ing, which is certainly a curious event in 
Windows programming. 

THE IN-BOX Please send your ques- 
tions, comments, and suggestions to me 
at any of these electronic mail addresses- 
PC MagNet: 72241,52 
MCI Mail: rduncan 
BIX: rduncan □ 



454 PC MAGAZINE SEPTEMBER 15, 1992 



Programming 



POWER PROGRAMMING 

The Windows 3 . 1 
ToolHelpDLL, Part 3 

BY RAY DUNCAN 



for the last two columns, we've 
been looking at Windows 3.1's 
TOOLHELP.DLL, a dynamic 
link library that gives you access 
to previously undocumented 
Windows data structures and 
function calls. Two sample pro- 
grams described in the August 
1992 issue— BADAPP and 
BADAPP2 — showed how to implement 
a notification callback routine that will be 
called by TOOLHELP if your program 
makes a function call with an invalid pa- 
imeter. SYSMON, published in the Sep- 
tember 15, 1992, issue, demonstrated 
how to use the TOOLHELP functions to 
walk the system module list, task list, win- 
dow class list, and global heap. 

In this installment, we'll examine the 
TOOLHELP functions that let your pro- 
gram intercept certain interrupts — such 
as divide by zero, general protection 
(GP) fault, breakpoint, and invalid 
opcode — in a "well-behaved" manner. 
The ability to capture and service these 
interrupts is vital for anyone who wants 
to write a Windows-based debugger, but 
it's also handy if you're writing any sort 
of high-level language interpreter or even 
an application with a built-in macro lan- 
guage. Any time you place a program- 
ming facility — especially one that sup- 
ports pointers — in the hands of an end- 
user, you can no longer hope to test your 
application exhaustively, so you must 
fight back with robust error handling. 

INTERRUPTS AND THEIR KIN As every 
English schoolboy knows, the Intel 80x86 
family of processors supports 256 levels 
of interrupts. The location of the inter- 
jpt service routine (ISR), or interrupt 
handler, for each interrupt is specified in 
a RAM-based table that is created and 
updated by software and interpreted by 



hardware. In real mode, the table is called 
the interrupt vector table; it is always lo- 
cated at address 0000:0000 and consists 
of 256 far pointers, or 1,024 bytes. In pro- 
tected mode, on the other hand, the table 
is called the Interrupt Descriptor Table 
(IDT). An IDT is more complex than a 
real-mode vector table, it can be located 
anywhere in memory, and it can be main- 
tained on a per-task basis. When an inter- 

Our examination of 
ToolHelp continues with 
a look at the functions 

that let applications 
intercept interrupts in a 
well-behaved manner. 



rupt occurs, the CPU is hardwired to push 
the current contents of the CPU flags and 
instruction pointer (CS:IP) onto the 
stack, fetch the address of the interrupt 
handler from the appropriate table ac- 
cording to the current execution mode, 
and load that address into the instruction 
pointer. When the handler routine is fin- 
ished, it executes an interrupt return 
(IRET) instruction, and execution re- 
sumes at the point of interrupt. 

So far, so good. But this explanation 
doesn't take into account that there are 
two basic classes of interrupts. External 
interrupts are the kind we generally think 
of when we hear the word interrupt; they 
are generated by adapter cards, clock 
chips, and other gizmos located outside 
the CPU chip. These devices usually in- 
terrupt the CPU by signaling it through 



the INTR pin; if the CPU accepts the in- 
terrupt by a pulse on the "interrupt ac- 
knowledge" (INTA) pin, the external de- 
vice tells the CPU which interrupt 
handler to use by jamming a number in 
the range to 255 onto the CPU's data 
bus. (There is also a nonmaskable inter- 
rupt pin, NMI, which we'll ignore here.) 

In real mode, a program can mask — 
or block the reception of — external inter- 
rupts by executing the DI (disable inter- 
rupts) instruction, and can unmask inter- 
rupts by executing the EI (enable 
interrupts) instruction. In protected 
mode, execution of EI and DI is mostly 
reserved for the operating system and its 
device drivers, though certain protected 
mode applications with I/O privilege 
level (IOPL) may also be allowed to exe- 
cute the instructions, and real mode ap- 
plications running in a Virtual 86 ma- 
chine will get special treatment. 

Internal interrupts, on the other hand, 
are triggered by events inside the CPU — 
the execution of an instruction, or an er- 
ror condition that arises during the exe- 
cution of an instruction. The one we're 
all familiar with is the INT instruction, 
which can be used in real mode to force 
the occurrence of any of the 256 possible 
interrupts. MS-DOS uses INT as its appli- 
cation program interface mechanism: 
When DOS boots up, it puts the address 
of its entry point into slot 21h of the inter- 
rupt vector table, and programs request 
services from DOS by loading various pa- 
rameters into registers and then execut- 
ing an INT 21h instruction to transfer 
control to DOS's function dispatcher. 

The neatest thing about the INT in- 
struction, aside from its use as a sort of 
compact FAR CALL instruction, is that 
it makes the initial testing of handlers for 
external interrupts much easier: You can 
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it with a small test program that executes 
the appropriate INT instruction under a 
variety of conditions, even if the external 
hardware that will ultimately generate 
the interrupt has not yet been built. 

But there's a lot more to internal inter- 
rupts than the INT instruction. There's 
the special 1-byte debugger breakpoint 
opcode, OCCh, which always generates 
an interrupt 3. There's interrupt 1, the 
single-step interrupt also designed espe- 
cially for use by debuggers. And finally, 
there's the whole host of interrupts 
(known by the specific technical term ex- 
ceptions) listed in Figure 1 that occur 
when a program tries to execute an in- 
struction with the wrong parameters or 
an instruction it isn't entitled to use. 

Most of these exceptions are of inter- 
est only to the authors of protected mode 
operating systems, and their implementa- 
tion varies from one model of the Intel 
80x86 series to another. When they occur 
in the context of an application program, 
the operating system's response is usually 
to terminate the application with extreme 
prejudice and put a discouraging message 
up on the screen to let the user know he 
just lost all his work. For a more detailed 
explanation, consult Programming the 
80386 by Crawford and Gelsinger (Sybex 
Inc., 1987), or Programmer's Reference 
Manual: The Processor and Coprocessor 
by Robert Hummel (Ziff-Davis Press. 
1992). Note that exceptions are further 
subdivided into two groups: faults and 





Exceptions 


Interrupt 


Description 





Divide by zero 


4 


Overflow 


5 


BOUND range exceeded 


6 


Invalid opcode 


7 


Coprocessor not available 


8 


Double-fault 


9 


Coprocessor segment overrun 


10(0Ah) 


Invalid task segment 


11 (OBh) 


Segment not present 


12(0Ch) 


Stack fault 


13(0Dh) 


General protection fault 


14(0Eh) 


Page fault 


16(10h) 


Coprocessor error 


i7(iih) 


Alignment check 



Figure 1: These interrupts, known as exceptions, 
occur when a program tries to execute invalid 
instructions. 



essentially that faulting instructions are 
restartable: trapping instructions are not. 

When an instruction faults, the error 
condition is detected by the CPU before 
any part of the instruction executes, and 
the address of the "bad" instruction itself 
is pushed onto the stack. This gives the 
interrupt handler the opportunity to re- 
cover from the error condition: It can re- 
trieve the address of the faulting instruc- 
tion from the stack, decode the 
instruction type, examine the registers or 
memory being accessed by the instruc- 
tion, make any changes that are neces- 
sary, and, finally, restart execution of the 
failed instruction by executing an IRET. 
At the least, the handler for a fault excep- 
tion can gather and display very detailed 
diagnostic information. In contrast, a trap 
exception isn't detected until after the er- 
ror has occurred, and the CPU pushes the 
address of the instruction after the failed 
instruction onto the stack. Because Intel 
80x86 instructions have varying lengths, 
and the trapped instruction may have al- 
ready changed registers and/or memory, 
recovering from a trap exception would 
be a nasty proposition. Fortunately, most 
Intel 80x86 exceptions are faults. 

HANDLING FAULTS TOOLHELP.DLL 
provides applications with access to a 
subset of the possible exceptions: inter- 
rupts 0, 1, 3, 6, 12, 13, and 14. For most 
applications, only two are worrisome: In- 
terrupt (divide by zero) and Interrupt 
13 (general protection fault). Interrupt 
is triggered if your program executes ei- 
ther a division by zero operation or a divi- 
sion that results in an overflow; that is, 
the quotient will not fit into the destina- 
tion register. Interrupt 13 is triggered by 
a wide variety of conditions, the most 
common of which are use of an invalid 
selector (such as dereferencing an unini- 
tialized or NULL far pointer) or using a 
valid selector but an offset that lies out- 
side the designated segment's "limit" 
(which is from 1 to 65536 bytes). 

The framework for application excep- 
tion handling with TOOLHELP is quite 
similar to the technique we used for the 
handling of parameter validation errors 
in BADAPP2.C: 

• The program must contain a callback 
routine, which is entered from TOOL- 
HELP when an exception is detected. 

• The callback routine must be 



• The initialization code for the applic. 
tion must allocate a thunk for the call- 
back routine with MakeProcInstanceQ. 
and register the callback with TOOL- 
HELP by calling InterruptRegister(). 

• The termination code for the applica- 
tion must notify TOOLHELP that it no 
longer wants to handle exceptions by call- 
ing InterruptUnRegisterQ, and then free 
the callback thunk by calling FreeProc- 
Instance(). 

When the application's callback rou- 
tine is entered, information about the 
cause of the exception is available on the 
stack (Figure 2). The state of all general 
registers at entry is indeterminate, except 
that AX has been loaded by the thunk 
code with the selector for the applica- 
tion's DGROUP. After examining the 
stack, the callback routine can take one 
of four possible actions: 

• Indicate that it doesn't want to handle 
the exception by executing a RETF in- 
struction: the exception will then be pro- 
cessed by the next handler on the chain 
(usually TOOLHELP itself). 

• Fix the cause of the fault, discard tf 
first 10 bytes of the stack, and execute ai„ 
IRET instruction to restart execution of 
the faulted instruction. 

• Call TerminateApp() to kill the fault- 
ing application. 

• Retain control by initializing all general 
and segment registers to valid values and 
then branching to an error-handling rou- 
tine in the application, never executing 
a RETF or IRET. 

Due to the design of the TOOLHELP 
interface, some of this is tough to imple- 
ment in a high-level language, so Win- 

The Stack After 
an Exception 



. (application's stack) 



Flags (fault) 


SP+OEH 


CS (fault) 


SP+OCH 


IP (fault) 


SP+OAH 


TOOLHELP handle (internal) 


SP+08H 


Interrupt Number 


SP+06H 


AX (at point of fault) 


SP+04H 


CS (TOOLHELP) 


SP+02H 


IP (TOOLHELP) 


SP+OOH 



Figure 2: This shows the stack contents at entry to 
an application interrupt callback routine. 
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dows application interrupt callbacks are 
ypically written either entirely in assem- 
bly language or as an assembly language 
stub that in turn calls a C routine to do 
the body of the work. 

And now we must turn to the truly 
horrid aspect of the TOOLHELP inter- 
face. Because Windows does not take full 



advantage of the Intel 80x86 protection 
architecture and runs all applications on 
the same Local Descriptor Table (LDT), 
Windows has no way to dispatch excep- 
tions on a per-application basis. As a re- 
sult, when your application registers an 
interrupt callback routine, that routine 
will receive callbacks for all exceptions 



that occur in the system — whether or not 
your own application caused them. This 
means that your application must main- 
tain internal flags that can be tested by 
the callback to determine whether the ex- 
ception should be handled or ignored, 
and update these flags each time the ap- 
plication gains or yields control of the 



BADAPP3.C 

Partial Listing 



ft BADAPP3 - Application Error Testbed for Windows 3.1 with Notification 

// Callback and GP Fault/Divide by Zero Interrupt Handlers 

// Copyright (C) 1992 Ray Duncan 

// Ziff Davis Publishing * PC Magazine 



#define dim(x) (sizeof(x) / sizeof (x [ 0] ) ) // returns 

# include "windows .h" 
# include "toolhelp.h" 
# inc lude " badapp . h " 



of elements 



HANDLE hlnst; 
HWND hFrame ; 

WNDPROC lpNotifyCallback; 
WNDPROC lpIntCallback ,- 

UINT ActiveFlag = FALSE; 
CATCHBUF CatchBuf; 

LPCATCHBUF IpCatchBuf = iCatchBuf; 
UINT IntNum ,- 
LPVOID IpFault; 

char szShortAppName[] = "BadApp" ; 

char szAppName[] = "BadApp - UAE Tester" 

char szMenuName [ ] = " BadAppMenu " ,- 

char szIconName[] = "BadAppIcon" ; 

struct decodeWord { 
UINT Code; 

LONG ("Fxn) (HWND, UINT, UINT, LONG); 



/ / module instance handle 

// handle for frame window 

// NotifyCaliback thunk addr 

// intcallback thunk addr 

// TRUE when handler active 

// holds Catch O state 

// far pointer for Throwf) 

// interrupt number 

// address of fault 

// short application name 

// long application name 

/ / name of menu resource 

// name of icon resource 

// structure associates 

// messages or menu IDs 

// with a function 



II 

It Table of window 
// and the functioi 
// 

struct decodeWord messages!] 
, DoNotifyMessage, 
0, DoIntMessage, 
WM^PAINT, DoPaint, 
WM_COMMAND , DoCommand , 
WM_DESTROY, DoDestroy, } 



usages supported by FrameWndProc { ) 
which correspond to each message. 



rf menubar item IDs and their corresponding functions. 



// 

// Table 

// 

struct decodeWord menuitems [ ] = 
IDM_EXIT , DoMenuExi fc , 
IDM_GPFAULT, DoMenuGPFault, 
IDM_HANG, DoMenuHang, 
IDM„ZERODIV, DoMenuZeroDiv, 
IDM_BADHDC, DoMenuBadHDC , 
I DM ,BADPTR. DoMenuBadPtr , } 



// WinMainO omitted here - same as BADAPP2 



// Initlnstance 



code for this application. 



BOOL Initlnstance (HANDLE hlnstance, int nCmdShow) 



hFrarae = CreateWindow ( 


II 


create frame window 


s z Shor t AppName , 


II 


window class name 


szAppName, 


II 


text for title bar 


WS_OVERLAPPEDWINDOW , 


II 


window style 


CW_US ED E FAULT , CW_USEDEFAULT , 


II 


default position 


CW_US EDE FAULT , CW_USEDEFAULT , 


II 


default size 


NULL, 


II 


no parent window 


NULL, 


II 


use class default menu 


hlnstance, 


II 


window owner 


NULL) ; 


II 


unused pointer 


if(!hFrame) return (FALSE) ; 


II 


error, can't create window 


ShowWindow {hFrame, nCmdShow) ; 


II 


make frame window visible 


UpdateWindow(hFrame) ,- 


II 


force WM_PAINT message 


// allocate private message numbers I 




i by callbacks 



messages [0) .Code 
messages [1] .Code 



Register WindowMessage ( " BADAPP_NOTIFY" ) ; 
Regis terWindowMessage ( " BADAPP_INTERRUPT " ) ; 



// allocate thunks for callbacks 

lpNotifyCallback = MakeProcInstance ( (WNDPROC) Notif yCallback, hlnst); 
lpIntCallback = MakeProcInstance ( (WNDPROC) ISR, hlnst); 



// register parameter validation and interrupt callbacks 
Notif yRegister (NULL, lpNotifyCallback, NF_NORMAL) ; 
InterruptRegister (NULL, lpIntCallback) ; 

return (TRUE) ; / / retu: 



// Termlnstance -- instance termination code for this application. 



BOOL Termlnstance (HANDLE hinstance) 
{ 

Notif yUnRegister (NULL) ; 
InterruptUnRegister (NULL) ; 
FreeProcInstancel lpNotifyCallback) ; 
FreeProcInstance(lpIntCallback) ; 
return (TRUE) ; 



// free validation callback 

// free interrupt callback 

// release callback thunks 

// return success flag 



// FrameWndProc callback function for application frame window. 

// 

LONG FAR APIENTRY FrameWndProc (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 



int i; 
long 1 ; 



ActiveFlag = TRUE; 
if (Catch(lpCatchBuf) ) 



// scratch variables 

// turn on exception handling 
// save context, or... 



// if regaining control from Throwf), exception occurred during 
II message handling. Send exception message, turn off exception 
// handling, and pass message to default handler. 
PostMessage (hFrame, messagesfl] .Code, 0, 0) ; 
ActiveFlag = FALSE ,- 

return (DefWindowProc (hWnd, wMsg, wParam, lParam) ) ; 



// decode window message and 
// run corresponding function 



if(wMsg == messagesti] .Code) 



1 = (*messages[i} .Fxn) (hWnd, wMsg, wParam, lParam); 
ActiveFlag = FALSE; // turn off exception handling 

return(l); // return message result 



} 



// if no match in messages [ ] table, turn off exception handling 
// and pass message to default message handler 
ActiveFlag = FALSE; 

return(DefWindowProc (hWnd, wMsg, wParam, lParam) ) ,- 



// DoCommandO, DoPaint () , and various routines 
// omitted here - see BADAPP and BADAPP 2 



// 

// DoIntMessage -- process private message from interrupt handler 

// 

LONG DoIntMessage (HWND hWnd, UINT wMsg, UINT wParam, LONG lParam) 

{ 

char temp[256],- // formatting buffer 

format and display interrupt number and fault address 
wsprintf (temp, "Interrupt %02Xh at %04X: %04Xh" , IntNum, 

HIWORD(lpFault) , LOWORD ( IpFault) ) ; 
MessageBox(hWnd, temp, "BadApp", MB_OK j MB_ICONEXCLAMATION) ; 

return (FALSE) ; 



// InterruptCallback -- callback routine for faults & exceptions. 
// Entered from "umbrella interrupt handler" in ISR. ASM. Restores 
// execution context to that' saved in the latest call to Catch () . 

// 

VOID FAR APIENTRY InterruptCallback (UINT Num. LPVOID Addr) 



IntNum = Num; 
IpFault = Addr; 
Throw ( IpCatchBuf . 1 ) ; 



// save interrupt number 

// and fault address 

// then restore old context. 



Figure 3: Extracts from BADAPP3.G showing the portions concerned with exception handling. The full 



code can be downloaded from PC MagNet. 
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CPU. This becomes a major maintenance 
problem in a hurry, particularly for com- 
plex applications that are implemented as 
a suite of discrete tasks communicating 
via DDE or SendMessage(). 

AN EXAMPLE To illustrate the funda- 
mental steps involved with TOOLHELP- 
based application exception handling un- 
der Windows, I've modified BADAPP2 
to create a new program — BADAPP3 — 
that includes an interrupt callback rou- 
tine. From a user's point of view, BAD- 
APP3 looks just like BADAPP and 
BADAPP2, except that when the user 
picks GP Fault, Divide by Zero, or Pass 
Bad Pointer on the Crash pop-up menu, 
he sees a diagnostic dialog box that origi- 
nates in BADAPP3, rather than one dis- 
played by Dr. Watson or the Windows 
kernel. And BADAPP3 cannot be ter- 
minated unilaterally by the operating sys- 
tem. Extracts from the source code for 
BADAPP3 that are relevant to the han- 
dling of exceptions are shown in Figure 

3, and the assembly language source code 
for the callback stub is shown in Figure 

4. A screen shot of BADAPP3 in action 
is shown in Figure 5. You can download 
the complete source code for B ADAPP3, 
along with the precompiled executable 
program (archived as BADAP3.ZIP) 
from PC MagNet. 

The overall structure of BADAPP3 is 
table-driven and straightforward, but 
there are two areas to note. The first is 
the method by which we keep control and 
restore the CPU to a known state when 
our callback routine is called because of 
a divide by zero or general protection 
fault that occurred in our application. 
When the callback is entered from 
TOOLHELP. we can figure out where 
the fault occurred easily enough, but the 
register contents and especially the depth 
of the stack are unpredictable. Executing 
a Goto to some error routine in our pro- 
gram would not be an adequate response, 
mainly because it wouldn't reset the stack 
and several faults in a row might cause 
the stack to overflow (resulting in yet an- 
other, more difficult to handle excep- 
tion). However, we can easily overcome 
this problem by exploiting the little- 
known Windows functions Catch() and 
Throw(). 

Catch() and Throw() form a general- 
purpose mechanism for structured excep- 
tion handling. You call CatchQ at some 



convenient central point in your program 
to save the current execution environ- 
ment, including all CPU registers in a 
structure of type CATCHBUF. When 
Catch() is invoked in this way, it returns 
a value of zero. At some future point in 
the execution of your program, when you 
find yourself in a hopeless situation, you 
can call ThrowQ with the address of the 
CATCHBUF structure and an arbitrary 
value that can be anything but zero. Then 
something magical happens: The CPU 
state including the stack pointer is re- 
stored according to the contents of the 
CATCHBUF structure, and execution 
continues by "returning" from the origi- 



; ISR. ASM - umbrella interrupt handler 

; Copyright (C) 1992 Ray Duncan 

; PC Magazine * Ziff Davis Publishing 





extrn 


INTERRUPTCALLBACK : far 


DGROUP 


group 


_DATA 


_DATA 


segment 


word public 'DATA' 




extrn 


_ActiveFlag : word 


_DATA 


ends 




_TEXT 


segment word public 'CODE' 




assume 


c s : _TEXT , ds : DGROUP 


ISR 


public 
proc 


ISR 
far 




push 
push 
mov 
mov 


ds 
bp 

bp, sp 
ds, ax 




test 
jz 


„ActiveFlag, -1 
ISR2 




cmp 
je 
cmp 
jne 


word ptr [bp+0ah],0 
I SRI 

word ptr [bp+0ah] , 0dh 
ISR2 


ISR1: 


push 
push 
push 


[bp+0ah] 
[bp+10h] 
[bp+0eh] 




call 


INTERRUPTCALLBACK 


ISR2 : 


pop 
pop 
ret 


bp 
ds 


ISR 


endp 




_TEXT 


ends 
end 





nal call to Catch() — except that the vakr 
of Catch() this time is whatever yo 
passed to Throw(). You distinguish the 
two possible types of return from Catch() 
by framing Catch() in an if{) structure: 

CATCHBUF CatchBuf; 



if ( Catch UCatchBuf ) 
{ 

//we got here 
/ / by a Throw ( ) 

} 



for BADAPP3 




; point to stack frame 

; make DGROUP addressable 

; is interrupt handling active? 

; no, jump 

; check for Int 

; (divide by zero) or 

; Int 0DH (GP fault) 

; jump if neither of these 

,- push interrupt number and 

; far pointer to faulting 

; instruction 

; transfer to C routine 

; if not GP fault or divide by 

; zero, let TOOLHELP handle it 



Figure 4: The assembly language stub entered by a far call from TOOLHELP when an exception is detected. 
This code checks whether the exception should be serviced, and if so, passes control to the main handler 
written in C. 



ISR. ASM 

Complete Listing 
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figure 5: This is the dialog box displayed by BADAPP3 when a 
general protection fault is detected. 



else 
{ 



// this was a return 
// from an intentional 
// call to Catch () 



// bad error detected, 
'/ bail out of our current 
// hopeless state 
Throw (StCatchBuf, 1) ; 

The call to Catch() in BADAPP3 is 
located right in the frame window's mes- 
sage handler. Since Windows programs 
are message- driven, we can safely assume 
that a divide by zero or general protec- 
tion fault is going to occur in some code 
that executes in response to a message. 
Therefore, we call Catch() immediately 
before decoding a message and handing 
it off to any internal subroutine. If a fault 
occurs, our assembly language stub, ISR, 
is entered, which in turn calls the C rou- 
tine InterruptHandler(). Interrupt- 
HandlerQ saves the interrupt number 
and location of the faulting instruction 
for later display, then calls Throw(), and 
the CPU reverts to its state at Catch(). 
We are then free to back out of the situa- 
tion by posting a private message to our- 
selves indicating that an error occurred, 
then handing the message to Windows' 
default message handler (DefWindow- 
p roc) instead of our own handler (since 
ur own handler is now known to fault 
on the same message). Hy the time we 
have processed the private error mes- 
sage, the application state has been 



cleaned up enough so that we 
can safely display a dialog box 
about the error. 

The other aspect of BAD- 
APP3 you may want to ponder 
and critique is the strategy for 
letting the exception callback 
know whether the application 
is currently in control. BAD- 
APP3 has a global, static-varia- 
ble, called ActiveFlag, which is 
updated by the body of the pro- 
gram and checked by the stub 
routine ISR. I initially consid- 
ered turning ActiveFlag on and 
off in the program's main event 
loop; that is, turning ActiveFlag 
off before a call to GetMessage(), and 
turning it on again upon return from 
GetMessage(). Then it occurred to me 
that in the worst case (though not in this 
particular program), forced execution of 
another task that might be responsible 
for an exception could quite easily be hid- 
den within the call to DispatchMes- 
sage() — for example, if one of the appli- 
cation's window message handlers called 
SendMessage(). Therefore, I decided to 
maintain the state of ActiveFlag within 
the window message callback routine in- 
stead, setting the flag to TRUE whenever 
an internal routine is explicitly run in re- 
sponse to a message, and setting it to 
FALSE before calling DefWindowProc 
or returning from the message callback. 
This approach could easily be extended 
by adding a new member to the mes- 
sages [] structure that defines the state of 
ActiveFlag — and thus the handling of ex- 
ceptions — on a per-message basis. 

FURTHER READING A very helpful tuto- 
rial on TOOLHELP.DLL exception 
handling, written by Kraig Brockschmidt 
of Microsoft Developer Relations, can 
be downloaded from the WINSDK fo- 
rum on CompuServe in the file 
FAULTW.ZIP. I found the technique of 
using Catch() and ThrowQ in a Windows 
application exception handler in this doc- 
ument. 

THE IN-BOX Please send your ques- 
tions, comments, and suggestions to me 
at any of the following electronic mail 
addresses: 

PCMagNet: 72241,52 
MCI Mail: rduncan 
BIX: rduncan 

Internet: duncan@csmcmvax.bitnet □ 
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Computers, FCC 
Class A, Class B, 
and You — 

or when is it 
better to get a 

B than an A? 

You need to know the difference 
between computers that meet the 
FCC class B radio frequency emis- 
sions standards and those that meet 
only the Class A standards. 

Computers emit radio signals in their 
operation. Because these signals 
may cause interference to radio and 
television reception, the marketing 
and the use of computers is regulat- 
ed by the Federal Communications 
Commission. Under federal rules, 
computer users are responsible for 
remedying interference, including 
interference in neighboring homes. 

Computers certified by the FCC as 
meeting the Class B standard are 
less likely to cause interference to 
radio and TV reception than those 
that have been verified by the man- 
ufacturer or importer to the Class A 
standards. Only Class B certified 
computers may be advertised, sold, 
or leased for use in residences. A 
similar regulatory program applies in 
Canada. 

Buyers seeking computers for use in 
homes (including offices at home) 
should shop for computers and 
peripherals which have been Class B 
certified. These devices carry a label 
with an FCC ID number. Both new 
and used Class A verified devices 
may be sold only for use in com- 
mercial and industrial locations. 
Signals from computers are more 
likely to be masked by electrical 
noise from other equipment in such 
an environment. These areas are 
also likely to have fewer radios and 
TVs. Accordingly, equipment mar- 
keted only for use in these locations 
may meet the less rigorous Class A 
standard. Class B certified equip- 
ment may be marketed for use in 
residences as well as commercial 
and industrial locations. 

As you shop for a computer for use 
in your home, look for the FCC clas- 
sification in the specifications or ask 
your vendor to recommend only ma- 
chines thai have been ceitified to the 
Class B limits. TV viewers and radio 
listeners in your home and in neigh- 
boring homes will be glad you did. 
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1-23 for DOS Release 2.4. 



1-2-3® is not only easier to learn and use, 
ife simply faster than any other DOS 
spreadsheet, including QuattrcfPro 
Release 4.0, especially on IBM" XTs 
and 286 machines. 

Ife the only DOS spreadsheet 
to offer Smartlcons™- a unique pal- 
ette of over 75 icons, 12 of which are 
customizable, giving you instant, 
one-click access to your most com- 
monly performed spreadsheet 
tasks. Smartlcons give 
you all the ease-of-use 
and graphical advan- 
tages of our Windows™ 
applications, without 
the need to change 
operating systems. And 
1-2-3 for DOS also gives you 
such unique 1-2-3 features as file 
Viewer, Auditor and Backsolver, a 
quicker and more efficient goal- 
seeker. And only 1-2-3 for DOS 
offers true compatibility with all 

Only 1-2-8 offers Smartlconsfor true one-click access Versions Of 

to virtually all your spreadsheet tasks, unlike tlie 1-2-3 aCTOSS 
limited SpeedBar' " in Quatlro l-ro which requires , ,p 

you to work through a menu tr& i piatlOrmS. 



And right now, you can get both 1-2-3 for 
DOS Release 2.4 and Freelance Graphics® 
for DOS Release 4.0, our presentation graph- 
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H A Competitive Comparison 



NSTL. Benchmark Tests 



NSTL benchmark tests on a 286 computer with 
640K prove that 1 -2-3 lor DOS R2.4 is much 
than QuattroPro 4.0. 
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1 -2-3 has significantly more market share . 
than all other DOS spreadsheets combined, 
which means 1 -2-3 is the spreadsheet of 
choice And with 1 8 million 1 -2-3 users, 

more people already know how to use the product, which saves time and money in training 
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Performance tests prove thai 1-2-3 for DOS Release 2.4 beats 
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ics package, together for just 
$229-a suggested retail value 
of $645. For a free auto demo 
or to order your upgrade 
directly from Lotus® call* 
1-800 TRADEUP, Ext 
7014. Or visit your 
Lotus Authorized 
Reseller. 
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Now you can print reports in 
landscape mode on aU printers, 
including dot matrix printers. 
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